home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 46 / Amiga Format CD46 (1999-10-20)(Future Publishing)(GB)[!][issue 1999-12].iso / -serious- / misc / installer / gui api / readme
Encoding:
Text File  |  1999-09-06  |  2.7 KB  |  52 lines
  1. The InstallerNG provides a GUI-API. This API (Aplication Programming
  2. Interface) defines an interface, such that the InstallerNG can have
  3. any GUI. If you want to build a new GUI, you have to write a
  4. shared-library, which has to provide some functions. These functions
  5. may become very complex, because they have to read/write from/to memory,
  6. which is owned by the InstallerNG process. Such memory areas are the
  7. global interpretation environment, which keeps values like the DEFUSER,
  8. LOGFILE, PRETENDMODE etc... Additionally, some functions get a local
  9. environment (like ASKFILE, ASKBOOL, ...), where the parameters, e.g.
  10. the SOURCE, DEST, ad so on for ASKFILE are stored. If you have to access
  11. texts, use the text-array, which comes as an argument for the API function
  12. "igui_InitApp()". Have a look at the example source, which implements a
  13. simple MUI based API.
  14.  
  15. Furthermore, you find some makros and useful tools/functions. See
  16. the "savagelib" drawer for documentation.
  17.  
  18. Note: be prepared to add some media related functions to the GUI
  19. (see the #?MEDIA functions of the installer); currently I am not
  20. sure, whether I define them as part of the API or not.....
  21.  
  22. RULES and HINTS
  23. ===============
  24. - start with a small structure, which describes your private GUI object,
  25.   this could hold window-pointers, gadget pointers etc...
  26.   now you can write the functions igui_InitApp() and igui_FreeApp()
  27.   and, after you have done so, you may start to implement the different
  28.   panels (i.e. write the igui_Ask#?() functions and the other stuff)
  29. - your gui could provide a menu; if so, you have to handle this by your
  30.   own, the InstallerNG itself does not care for that!
  31. - the GUI has to care for locking and unlocking itself; thus, unlock the
  32.   GUI before you have to wait (i.e. before you call igui_QuietWaitApp(),
  33.   which is also called by the InstallerNG itself) and lock the GUI before
  34.   you return from a function, which modified the GUI (like igui_Ask#?()
  35.   or igui_Message() or...)
  36. - have a look at the example source: there you find the documantation for
  37.   every API function and additional example source
  38. - never ever write to the arguments like the environment structures or
  39.   the text array -- they are read only! the only object you are allowed
  40.   to write to is your own custom application structure, which you create
  41.   with igui_InitApp() and which comes as argument for all the functions
  42. - handling GUI errors: if anything goes wrong (e.g. OpenWindow() fails)
  43.   you must set an error code anywhere in your private structure; return
  44.   this error code with igui_Error(), because InstallerNG calls this
  45.   function to check for success of any GUI function and quits, if
  46.   igui_Error() returns a non-zero result
  47.  
  48. Have fun,
  49. Jens
  50.  
  51.  
  52.